<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <title>uicontrol</title>
  </head>
  <body bgcolor="#FFFFFF">
    <center>Scilab Function</center>
    <div align="right">Last update : 03/11/2006</div>
    <p>
      <b>uicontrol</b> - create a Graphic User Interface
  object</p>
    <h3>
      <font color="blue">Calling Sequence</font>
    </h3>
    <dl>
      <dd>
        <tt>h = uicontrol('PropertyName',PropertyValue,...) h =
    uicontrol(parent,'PropertyName',PropertyValue,...)
    h=uicontrol(uich)</tt>
      </dd>
    </dl>
    <h3>
      <font color="blue">Description</font>
    </h3>
    <p>this routine creates an object in a figure. If the handle of the figure
    is given (as the first parameter), the uicontrol is created in this
    figure. If no handle is given, the uicontrol is created in the current
    figure ( which may be obtained with a call to gcf() ). If there is no
    current figure, then one is created before the creation of the uicontrol.
    Then when the control is created, the properties given as parameters are
    set with the coresponding values. It is equivalent to create the
    uicontrol, and then set its properties with the set() command.
    Nevertheless, it generally more efficient to set the properties in the
    call to uicontrol(). This is particularly true coincerning the 'style'
    field. Indeed, the default value for this property is 'pushbutton'. So if
    you do not set it at creation time, a button will be created, and will be
    transformed to another uicontrol when you call the get(h,'style', ... )
    instruction. Scilab and all the graphic objects communicate through the
    property mechanism. Thus, to create adapted uicontrol, one has to know the
    use of the property fields.</p>
    <p>h = uicontrol('PropertyName',PropertyValue,...) creates a uicontrol and
    assigns the specified properties and values to it. It assigns the default
    values to any properties you do not specify. The default uicontrol style
    is a pushbutton. The default parent is the current figure. See Properties
    for information about these and other properties.</p>
    <p>h = uicontrol(parent,'PropertyName',PropertyValue,...) creates a
    uicontrol in the object specified by the handle, parent. If you also
    specify a different value for the Parent property, the value of the Parent
    property takes precedence. parent is the handle of a figure.</p>
    <p>h=uicontrol(uich) gives focus to the uicontrol specified by the handle,
    uich.</p>
    <p>Those are described under:</p>
    <h3>
      <font color="blue">Properties</font>
    </h3>
    <dl>
      <dd>
        <li>
          <b>
            <font color="maroon">BackgroundColor</font>
          </b>[1,3] real vector or string Background color of the uicontrol. A
        color is specified as Red, Green and Blue values. Those values are
        real in [ 0,1]. The color can be given as a real vector, ie [R,G,B] or
        a string where each value is separated by a |, ie "R|G|B"</li>
        <li>
          <b>
            <font color="maroon">callback</font>
          </b>string String evaluated by the scilab interpreter when an
        usicontrol is activated. (for example when you click on a
        button).</li>
        <li>
          <b>
            <font color="maroon">fontangle</font>
          </b>string : {'normal'} | italic | oblique For a control containing
        some text, this property sets the slant of the font.</li>
        <li>
          <b>
            <font color="maroon">fontsize</font>
          </b>real For a control containing some text, this property sets the
        size of the font in FontUnits.</li>
        <li>
          <b>
            <font color="maroon">fontunits</font>
          </b>string : {points} | pixels | normalized For a control containing
        some text, this property sets the units with which the fontsize is
        specified.</li>
        <li>
          <b>
            <font color="maroon">fontweight</font>
          </b>string : light | {normal} | demi | bold For a control containing
        some text, this property sets the weight of the used font</li>
        <li>
          <b>
            <font color="maroon">fontname</font>
          </b>string : used to choose the name of the font selected to display
        the text of the control.</li>
        <li>
          <b>
            <font color="maroon">ForegroundColor</font>
          </b>[1,3] real vector or string Foreground color of the uicontrol. A
        color is specified as Red, Green and Blue values. Those values are
        real in [ 0,1]. The color can be given as a real vector, ie [R,G,B] or
        a string where each value is separated by a |, ie "R|G|B"</li>
        <li>
          <b>
            <font color="maroon">Horizontalalignment</font>
          </b>string: left | {center} | right. Set text horizontal alignment in
        the uicontrol. This property can only be used with 'text', 'edit' and
        'checkbox' styles.</li>
        <li>
          <b>
            <font color="maroon">ListboxTop</font>
          </b>integer For a ListBox, this property tells which item of the list
        appears on the first line of the visible area of the list.</li>
        <li>
          <b>
            <font color="maroon">Max</font>
          </b>scalar Specifies the largest value the 'value' property can be set
        to. It has however differnet meaning on each uicontrol:</li>
        <li>
          <b>
            <font color="maroon">o</font>
          </b>Check Boxes : Max is the value the 'value' property take when
        control is checked</li>
        <li>
          <b>
            <font color="maroon">o</font>
          </b>Silders : Maximinum value of the slider</li>
        <li>
          <b>
            <font color="maroon">o</font>
          </b>List boxes : if (Max-Min)&gt;1 the list allows multiple selection,
        Otherwise not.</li>
        <li>
          <b>
            <font color="maroon">Min</font>
          </b>scalar Specifies the lowest value the 'value' property can be set
        to. It has however different meaning on each uicontrol:</li>
        <li>
          <b>
            <font color="maroon">o</font>
          </b>Check Boxes : Min is the value the 'value' property take when
        control is unchecked</li>
        <li>
          <b>
            <font color="maroon">o</font>
          </b>Silders : Mininum value of the slider</li>
        <li>
          <b>
            <font color="maroon">o</font>
          </b>List boxes : if (Max-Min)&gt;1 the list allows multiple selection,
        Otherwise not.</li>
        <li>
          <b>
            <font color="maroon">Parent</font>
          </b>integer Handle of the control parent. Changing this property
        allows to move a control from a figure to another.</li>
        <li>
          <b>
            <font color="maroon">Path</font>
          </b>This property is read-only. It allows to get the TK path of the
        control as a string. (Useful when creating User Interfaces using
        uicontrols and TCL/TK scripts.)</li>
        <li>
          <b>
            <font color="maroon">Position</font>
          </b>[1,4] real vector or string. This property is used to set or get
        the geometrical configuration of a control. It is a real; vector : x y
        w h where the letters stand for the x location of the left bottom
        corner, the y location of the left bottom corner, the width and the
        height of the uicontrol. The unit is determined by the 'Unit'
        property.</li>
        <li>
          <b>
            <font color="maroon">SliderStep</font>
          </b>[1,2] real vector or string, [small big]. The small step represents
        the movement achieved when clicking on the slider trough
        or tapping on the keyboard arrows (when the slider has focus);
        the big step is the amount moved when using Ctrl-keyboard-arrows.
        If the big step is omitted, it is defaulted to 1/10 of the scale.</li>
        <li>
          <b>
            <font color="maroon">String</font>
          </b>string. Generally, this property represents the text appearing in a
        uicontrol. Its exact meaning sometimes depends on the uicontrol
        style:</li>
        <li>
          <b>
            <font color="maroon">o</font>
          </b>List Boxes, Popup Menu the value can be a vector of string or a
        string where the items are separated by a '|'.</li>
        <li>
          <b>
            <font color="maroon">Style</font>
          </b>string : {pushbutton} | radiobutton | checkbox | edit | text |
        slider | frame |listbox | popupmenu Style of the uicontrol. Here is a
        short description of each one:</li>
        <li>
          <b>
            <font color="maroon">o</font>
          </b>pushbutton A rectangular button generally used to run a
        callback.</li>
        <li>
          <b>
            <font color="maroon">o</font>
          </b>radiobutton A button whith to states : on or off.</li>
        <li>
          <b>
            <font color="maroon">o</font>
          </b>checkbox a small uicontrol that have to state : on or off</li>
        <li>
          <b>
            <font color="maroon">o</font>
          </b>edit an editable string control</li>
        <li>
          <b>
            <font color="maroon">o</font>
          </b>text a text control (generally static).</li>
        <li>
          <b>
            <font color="maroon">o</font>
          </b>slider a scale control, that is a scrollbar use to set values
        between in range with the mouse.</li>
        <li>
          <b>
            <font color="maroon">o</font>
          </b>frame a control representing a zone used to group of related
        controls.</li>
        <li>
          <b>
            <font color="maroon">o</font>
          </b>listbox a control representing a list of item that can be
        scrolled. The item can be selected with the mouse.</li>
        <li>
          <b>
            <font color="maroon">o</font>
          </b>popupmenu a button which make a menu appear when clicked.</li>
        <li>
          <b>
            <font color="maroon">Tag</font>
          </b>string this property is generally used to identify the control. It
        allows to give it a "name". Mainly used in conjontion with
        findobj().</li>
        <li>
          <b>
            <font color="maroon">Units</font>
          </b>string : {points} | pixels | normalized Set the units used to
        specify the 'position' property.</li>
        <li>
          <b>
            <font color="maroon">Userdata</font>
          </b>this can be used to associate some scilab objects (string,string
        matrix, matrix mxn) to an uicontrol. </li>
        <li>
          <b>
            <font color="maroon">Value</font>
          </b>Value of the uicontrol. The exact meaning depends on the style of
        the uicontrol.</li>
        <li>
          <b>
            <font color="maroon">o</font>
          </b>Check boxes, Radio buttons value is set to Max (see above) when on
        and Min when off.</li>
        <li>
          <b>
            <font color="maroon">o</font>
          </b>List Boxes, Popu Menu value is a vector of indexes corresponding
        to the index of the selected entry in the list. 1 is the first item of
        the list.</li>
        <li>
          <b>
            <font color="maroon">o</font>
          </b>Sliders value indicated by the slider bar.</li>
        <li>
          <b>
            <font color="maroon">Verticalalignment</font>
          </b>string: top | {middle} | bottom. Set text vertical alignment in
        the uicontrol. This property can only be used with 'text' and
        'checkbox' styles.</li>
      </dd>
    </dl>
    <h3>
      <font color="blue">Examples</font>
    </h3>
    <pre>f=figure();
// create a figure
h=uicontrol(f,'style','listbox', ...
 'position', [10 10 150 160]);
// create a listbox
set(h, 'string', "item 1|item 2|item3");
// fill the list
set(h, 'value', [1 3]);
// select item 1 and 3 in the list
close(f);
// close the figure
  </pre>
    <h3>
      <font color="blue">See Also</font>
    </h3>
    <p>
      <a href="figure.htm">
        <tt>
          <b>figure</b>
        </tt>
      </a>,&nbsp;&nbsp;<a href="../graphics/set.htm">
        <tt>
          <b>set</b>
        </tt>
      </a>,&nbsp;&nbsp;<a href="../graphics/get.htm">
        <tt>
          <b>get</b>
        </tt>
      </a>,&nbsp;&nbsp;<a href="uimenu.htm">
        <tt>
          <b>uimenu</b>
        </tt>
      </a>,&nbsp;&nbsp;</p>
    <h3>
      <font color="blue">Author</font>
    </h3>
    <p>Bertrand Guiheneuf</p>
  </body>
</html>
